NAME
cassio - tool for working with Atari 8-bit cassette images

SYNOPSIS
cassio [OPTIONS] image_file [serial_port]

DESCRIPTION
cassio is an emulator for the Atari 410/1010/XC11/XC12 cassette
drives, for use with an Atari 400/800/XL/XE computer and an SIO2PC
device. It allows the Atari to load cassette image (.cas) files
directly from the user's Linux (or other UN*X) system.

cassio is also a tool for creating, editing, analyzing, and repairing
cassette images.

OPTIONS
Options marked with [*] are usable in Image Editing Mode (see -E).

Long options may be abbreviated (e.g. --qui is the same as --quiet).

  --auto-pause
  -a             Auto-pause feature: When cassio encounters a block with
                 a long gap (PRWT > 10 seconds), it will automatically
                 enter Pause mode and wait for the user to un-pause (via
                 the space bar or Enter key). This may be helpful with
                 multi-stage images that use the motor control line,
                 particularly ones with an intro screen or menu that
                 requires user interaction (e.g. Ace of Aces)
                 - The first data record in any image is a long-gap record.
                 This will not cause auto-pause to be activated. Only the
                 second and subsequent long-gap records will auto-pause.
                 - This option only applies when keyboard controls are
                 enabled.

  --baud baud
  -b baud    [*] Set forced baud rate for SIO transfer
                 - Default: baud record(s) in image file, or 600 in
                 -c/-E/-o/-R modes, or if the image contains no
                 baud records.
                 - You may also use "std" for the baud rate to force
                 600 baud

  -B         [*] Set forced baud rate to 600bps (same as "-b600") or
                 "--baud=std"). Use to override non-standard baud records
                 in the image file.
                 - Note: Baud rates other than 600 are only supported
                 on Linux.

  --create file
  -c file        Create a .cas image containing the data from file.
                 Can be used with e.g. BASIC or data files. Can be used
                 with binary load files, but they are not converted to
                 boot tape format; for that, use xex2cas
                 - To write new .cas image to standard output, use "-"
                 for the file.
                 - For text or source code files, see -e.

  --delay seconds
  -d seconds [*] Add a delay to the tape leader (first PRWG).
                 Useful for images whose leader is too short,
                 or if your Atari is too far from your PC to reach it.
                 Equivalent to "-p3=(seconds*1000)"

  --description descrip
  -D descrip [*] Set the description on the new .cas image. Only usable
                 with -E (image editing) or -c (image creation) modes.

  --eol
  -e             EOL translations. With -c or -X, UNIX-style end of lines
                 are converted to Atari EOLs in the newly-created image.
                 With -o, Atari EOLs in the image will be converted to
                 UNIX-style EOLs in the dumped data.
                 - Useful for text files or BASIC/ASM/etc. source code.
                 To make an image compatible with ENTER "C:", also
                 use the -s4000 option.
                 - Without -c, -o, or -X, the -e option does nothing.

  --edit image.cas
  -E image.cas   Puts cassio in "image editing" mode: instead of sending
             [*] file to the serial port, cassio will create a new .cas
                 image file, incorporating any baud rate, PRWT timing,
                 and/or description changes caused by any options marked
                 with [*].

  --edit -
  -E-            In-place or filter image editing mode (see -E above).
                 - If image_file is given, -E's output is written
                 to same file name as image_file, and image_file is
                 renamed to end in "~"
                 - If reading from standard input (image_file not given,
                 or given as "-"), -E's output is written to standard
                 output, making cassio act as a filter.

  --fast
  -f         [*] "Fast Load (1.5x)" mode: same as "-b879 -l12000 -s200".
                 Faster than -m, but only compatible with 75-80% of images

  --ff-block block
  -F block   [*] Fast-forward to block before sending any data over the
                 serial port. Similar to -k option, but allows arbitrary
                 block number.
                 - Note: the -F option can be combined with -S (stop tape).
                 In this case, remember that "-S block" stops *after*
                 "block" has been processed. To play or process a single
                 block, give the same block number to both -F and -S.
                 - Giving a -F value greater than the -S value results in
                 NO blocks being played/processed!

  --help
  -h             Display this help message

  --force-atarisio
  -H             Hias mode: Serial port is actually an AtariSIO device.
                 Normally, cassio will auto-detect this, and switch to
                 the AtariSIO device automatically. Use -H, and supply
                 /dev/atarisio0 or /dev/atarisio1 as the serial port, if the
                 auto-detection gets confused. Only supported on Linux.

  --info
  -i             Print brief information about image. Displays block count,
                 size, stage count, and estimated load time, then exits
                 without doing any serial I/O.

  --details
  -I             Print detailed information about image. This goes through
                 the motions and prints the same information as a real
                 run, but does not attempt to do any serial I/O.
                 Enables -r option.
                 - Both -i and -I are useful for diagnosing a troublesome
                 image file without waiting for the Atari to load it.

  --ff-file
  --ff-stage
  -k stage   [*] Skip (fast forward) to file or stage # in the image.
                 Useful for tapes containing multiple files, or to skip
                 over a "cracked by" screen. Files/stages are numbered
                 beginning with 1; saying -k1 does nothing.

  --disable-keyboard
  -K             Disable interactive keyboard controls.
                 - Default: Controls enabled if stdin is a terminal, disabled
                 otherwise. Use -K option if detection fails.

  --long-gap millis
  -l millis  [*] Limit long PWRG (prewrite record gap) time to millisec.
                 - Default: unlimited (use PWRG timing from image file).

  --fix
  -L         [*] Force block length to 132, for any 133-byte block, and
                 repair short EOF or partial-data blocks.
                 - This is useful with .cas files created by wav2cas, which
                 sometimes adds an extra (mostly harmless) byte to some
                 records, and sometimes misses the last few bytes of the
                 last record.

  --medium
  -m         [*] "Medium Fast Load (1.3x)" mode: same as "-b853".
                 Not as fast as -f, but compatible with 90% of images

  --med-gap
  -M millis  [*] Force "medium length" PRWT time to millisec. A record
                 is considered medium length if its PRWT exceeds 400ms,
                 but is less than 9000ms. Such blocks are also known as
                 "normal IRG" blocks in Atari lingo. They are created by
                 e.g. SAVE or LIST (not CSAVE).

  --no-atarimax
  -n             Do not clear RTS before starting transfer.
                 For use with non-Atarimax SIO2PCs, but it shouldn't
                 actually be needed (included in the unlikely event that
                 some homebrew SIO2PC has trouble with the RTS line).

  --no-baud
  -N             Do not set the baud rate on the serial port at all. Can
                 be useful on unsupported systems where cassio doesn't
                 know how to set a non-standard baud rate (you set it
                 manually with e.g. 'stty' before running cassio)

  --dump file
  --extract file
  -o file        Save the data in the .cas image to file. For standard
                 132-byte tape blocks, the data will not include the
                 baud correction, control, or checksum bytes.
                 - To save data to standard output, use "-" for the file.
                 - For images containing text or source code, see -e.

  --patch block[=new_prwt][,block[=new_prwt]]...
  -p block[=new_prwt][,block[=new_prwt]]...
             [*] Set the PRWT for given block number to the given time
                 (given in milliseconds). If a new_prwt is not given,
                 it is assumed to be 15000 (15 seconds).
                 - To skip a block completely, set its PRWT to 0. The
                 block will not be sent to the Atari in playback mode,
                 and in edit mode, the output file will not contain this
                 block.
                 - Note that no spaces are allowed before or after the
                 comma(s) or equals sign(s).
                 - This option may occur more than once, but there is a
                 total limit of 1000 blocks for all the -p options.
                 Also, block numbers must be given in order on the
                 command line.
                 - Only data blocks are affected by -p; attempts to set
                 the PRWT of a FUJI, baud, or unknown block type will
                 be silently ignored.

  --progress-bar
  -P             Progress bar mode. With this option, detailed information
                 and warnings are not printed, though fatal errors still
                 are. If warnings occur, a count of warnings will be
                 printed after the load is complete. Option has no effect
                 in -c/-o/-R modes.

  --quiet
  -q             Quiet operation (do not emit progress messages on stderr).
                 (Errors and warnings will still be printed)

  --silent
  -Q             Really quiet operation: same as -q, but warnings are
                 also suppressed

  --scroll
  -r             Allow per-block progress reports to scroll, so you can
                 see them all after the load is done. Without this option,
                 each block's information overwrites the previous block's,
                 preventing the screen from scrolling, but also preventing
                 you from reviewing them. The -I option automatically
                 enables this option.

  --read-sio
  -R             Read mode: read data (NOT audio) from a real Atari tape
                 drive. Requires either a cassette drive that has been
                 modified with a motor control enable switch, or an Atari
                 computer on the SIO chain (use POKE 54018,52 to start
                 motor; POKE 54018,60 to stop).
                 - The data will be written as a standard .cas image
                 in image_file. This option may be used with the options
                 marked with [*]; the newly-created .cas file will have its
                 timing altered by these options, if present.
                 - The -R option has not been well-tested, and may be
                 overly susceptible to motor speed variations, stretched
                 tape, and dropouts. Try fiddling with the baud rate (-b)
                 if you encounter difficulties.
                 - The -R option is NOT supported in AtariSIO mode; you
                 must "rmmod atarisio" and use a /dev/ttyS* device.

  --short-gap millis
  -s millis  [*] Force short (<500ms) PWRG time to millisec
                 - Default: use PWRG timing from image file

  --stop-block block
  -S block   [*] Stop tape (exit cassio) after this block number.
                 See also note under -F.

  --adjust-timing [op][amount]
  -t [op][amount]
             [*] Timing adjust: Add/subtract/multiply PRWT times in ALL
                 data records by this much. Operators are +, -, *.
                 Amount is treated as a decimal factor for multiplication,
                 or as milliseconds for add/subtract.
                 - Examples: "-t+20" will add 20ms to every block,
                 "-t-30" will subtract 30ms from every block,
                 and -t*1.1 will multiply every block's time by 1.1

  --strip
  -U         [*] Remove unknown type records, in image editing (-E) mode.
                 May be combined with other options marked with [*].
                 Has no effect without -E.
                 - Normally, the .cas image created by -E will include
                 verbatim copies of any non-standard (non-FUJI/baud/data)
                 records in the input .cas image. This option strips them.
                 - In addition, this option will eliminate any extra FUJI
                 records (but not the initial FUJI record in block 1),
                 as well as any redundant baud records which set the baud
                 rate to the same value as the previous baud block.
                 - May be used to catenate several images into one, with
                 a single FUJI record and a single baud record (assuming
                 they are all 600 baud standard images, or the -B option is
                 used). Example:
                 - cat foo.cas bar.cas baz.cas | cassio -UE new.cas

  --verifile vfile.cas
  --compare vfile.cas
  -v vfile.cas   Verify (compare) image files. This compares only the
                 data (including baud/control/cksum bytes) of "vfile.cas"
                 with the data of "image_file".
                 - Without -q, blocks that
                 differ will be listed (with -x, their contents, too).
                 - PRWT/leader times are NOT compared. Exit status of cassio
                 will be 0 (success) if data in the files are identical,
                 or 1 (failure) otherwise, just like diff and cmp.
                 - Note: If you want to compare the file data in two images,
                 without the baud/control/cksum bytes, use -o to dump
                 the data to files, then use diff or cmp to compare them.

  --version
  -V             Print cassio version and compile time options, and exit

  --hexdump
  -x             Print a hex dump of the data blocks in the image, including
                 the header, control, and checksum bytes.
                 - By itself, -x implies -I, and prints hex dumps of
                   all data blocks.
                 - With -v: only print hex dumps of blocks that differ
                 - With -i: only print hex dumps of invalid blocks

  --split-stages file
  --split-files file
  -X file        Extract each stage/file to a separate file. Like -o, but
                 creates multiple files. The filenames will have the
                 string ".NN" appended, where NN is the 2-digit stage
                 number.
                 - The -e option may be useful for images containing text
                 files or source code.

  --normalize
  -z         [*] Normalize timing and fix 133-byte blocks. Equivalent to:
                 - -b600 -s260 -M4000 -l12000 -L

  --split-blocks
  -Z filename    Split .cas image into multiple files, one per block.
                 They will be called "filename.0001", "filename.0002",
                 et cetera. The filename may contain a directory component,
                 provided the directory already exists.
                 - Each of these files may be edited individually as
                 desired. To join them back together into a .cas image,
                 simpy use "cat filename.???? > file.cas".

  image_file     File to read .cas (cassette image) from. To read from
                 standard input, leave blank or use "-"

  serial_port    Device to write cassette data to. Normally a character
                 device (e.g. /dev/ttyS0 for 1st serial port), but may
                 be standard output instead.
                 - Default: /dev/ttyS0
                 - Fallback to /dev/atarisio0 if needed
                 - Use "-" to write to standard output.
                 - If a single digit is used for the serial port, it
                 will have "/dev/ttyS" prepended to it, so you can refer
                 to your serial ports as 0, 1, etc. instead of typing the
                 full device name. Also, if the serial port argument
                 doesn't begin with a "/", ".", or "-", the string "/dev/"
                 will be prepended.

Most options are applied in the order they appear on the command line.
This means that (for instance) you can use "-z -s250", which will set
the timing as -z, but override the implied "-s260" in the -z option,
giving an overall effect of "-b600 -s250 -M4000 -l12000 -L".

Exceptions: The -t option's effects are applied after any -z/-f/-m/-s/-M/-l
options, and the -p option's effects are applied after -t. Also, you
may only use one of -c/-E/-o/-R.

Options not taking arguments may be bundled. "-izxm3500" means the same as
"-i -z -x -M 3500"

With no arguments, cassio will read a .cas image from standard input and
write SIO data to /dev/ttyS0 using the baud rate and timing
specified in the image

KEYBOARD CONTROLS

During playback, the following controls are available:

P or Space - Pause/Play

R or , - Rewind 1 Block

B or < - Rewind to Beginning

F or . - Fast Forward 1 Block

Q or Escape - Exit

S or Enter - Skip current PRWT (send data immediately)

H or ? - This Help

Keyboard commands are not case-sensitive.

Keyboard controls are disabled if standard input is not a terminal
(e.g. redirected from a file or pipe), or if the -K option is used.

If Rewind, Rewind to Beginning, or Fast Forward are used, playback
will be paused after the requested action is taken, if it wasn't
already paused.

The Skip PRWT command does not enter pause mode. It's useful for the
impatient, on images that have long gaps between files/stages. If
Skip PRWT is used while in pause mode, it will exit pause mode and
start the playback at the data of the current block.

If a key is pressed while data is being written to the serial port
(while the W is displayed), it will not be acted on until the write
is complete (start of the PRWT of the next block).

Using the keyboard controls during quiet (-q/-Q) or progress bar (-P) modes
will cause cassio to switch back to the standard verbose mode.

NOTES

Not all Atari computers can handle baud rates other than 600. Most will
work up to 800-850 baud, though.

Some images contain a custom second-stage bootloader which uses its
own baud rate and custom tape format. These images may be incompatible
with the -f/-b/-B/-l/-s options. If you have trouble loading an image,
especially a commercial game, try it without any options.

There is no hardware support for the cassette motor control line on
the SIO2PC device, so cassio cannot stop the emulated tape when the
Atari wants to stop it. Most images do not need motor control. For the
ones that do, the -d and -p options can sometimes be used to work around
the problem.

There is no real support for saving data from the Atari (aka writing to
the emulated cassette deck), and for technical reasons, there probably
never will be. Save your files on a real tape or record your Atari's
audio output during a save, and try wav2cas; 
or else use an Atari tape deck with the -R option.

For more information, including usage examples, see the various
README_*.txt files in the cassio distribution (may also be installed
in /usr/share/doc/cassio-0.2.2)

BUGS

There are too many options to remember them all...

If you find any bugs, please report them to the author, so I can fix them

AUTHOR

B. Watson

urchlay [at] urchlay [dot] com

user Urchlay on www.atariage.com forums

SEE ALSO
cas2wav(1)
wav2cas(1)
cas2cas(1)
xex2cas(1)
- cassio Home Page: http://www.urchlay.com/cassio/
- AtariAge Atari 8-bit Forum:
	http://www.atariage.com/forums/index.php?showforum=12
- CAS Archive: http://cas-archive.pigwa.net
